Quoting the official Ion documentation:
Amazon Ion is a richly-typed, self-describing, hierarchical data serialization format offering interchangeable binary and text representations. The text format (a superset of JSON) is easy to read and author, supporting rapid prototyping.
The binary representation is efficient to store, transmit, and skip-scan parse.
The rich type system provides unambiguous semantics for longterm preservation of data which can survive multiple generations of software evolution.
Ion was built to address rapid development, decoupling, and efficiency challenges faced every day while engineering large-scale, service-oriented architectures.
<?=
ion\serialize([
"key" => "value",
"more" => [
"data" => 123
]
]);
?>
{key:"value",more:{data:123}}
If you now think that this looks a lot like JSON, you're probably right, because Ion is a superset of JSON:
<?=
json_encode([
"key" => "value",
"more" => [
"data" => 123
]
]);
?>
{"key":"value","more":{"data":123}}
So, all valid JSON is also valid Ion. Please refer to the official spec to learn more about this topic.
<?=
var_representation(
ion\unserialize('{key:"value",more:{data:123}}')
);
?>
[
'key' => 'value',
'more' => [
'data' => 123,
],
]
If you try the same with the JSON equivalent, you'll see that it's basically valid Ion, too:
<?=
var_representation(
ion\unserialize('{"key":"value","more":{"data":123}}')
);
?>
[
'key' => 'value',
'more' => [
'data' => 123,
],
]
Ion supports multiple sequences of documents within a single stream; consider the following:
<?=
var_representation(
ion\unserialize('
{"key":"value","more":{"data":123}}
{"key":"value","more":{"data":456}}
', new ion\Unserializer\Unserializer(multiSequence: true)
)
);
?>
[
[
'key' => 'value',
'more' => [
'data' => 123,
],
],
[
'key' => 'value',
'more' => [
'data' => 456,
],
],
]
Any Ion value can include one or more annotation symbols denoting the semantics of the content. This can be used to:
blob or clob value.In the text format, type annotations are denoted by a non-null symbol token and double-colons preceding any value. Multiple annotations on the same value are separated by double-colons:
int32::12 // Suggests 32 bits as end-user type
degrees::'celsius'::100 // You can have multiple annotaions on a value
'my.custom.type' :: { x : 12 , y : -1 } // Gives a struct a user-defined type
{ field: some_annotation::value } // Field's name must precede annotations of its value
jpeg :: {{ ... }} // Indicates the blob contains jpeg data
bool :: null.int // A very misleading annotation on the integer null
'' :: 1 // An empty annotation
null.symbol :: 1 // ERROR: type annotation cannot be null
Except for a small number of predefined system and PHP annotations, Ion itself neither defines nor validates such annotations; that behavior is left to applications or tools (such as schema validators).
It’s important to understand that annotations are symbol tokens, not symbol values. That means they do not have annotations themselves. In particular, the text a::c is a single value consisting of three textual tokens (a symbol, a double-colon, and another symbol); the first symbol token is an annotation on the value, and the second is the content of the value.
<?php
foreach (ion\Symbol\System::cases() as $e) {
printf("%30s:: => %s\n", $e->value, $e->name);
}
/*
$ion:: => Ion
$ion_1_0:: => Ivm_1_0
$ion_symbol_table:: => IonSymbolTable
name:: => Name
version:: => Version
imports:: => Imports
symbols:: => Symbols
max_id:: => MaxId
$ion_shared_symbol_table:: => SharedSymbolTable
*/
?>
There are two handful of annotations used by PHP, which are centralized in the ion\Symbol\PHP enumeration:
<?php
foreach (ion\Symbol\PHP::cases() as $e) {
printf("%3s:: => %s\n", $e->value, $e->name);
}
/*
PHP:: => PHP
R:: => Reference
r:: => Backref
p:: => Property
o:: => Object
c:: => ClassObject
O:: => MagicObject
C:: => CustomObject
E:: => Enum
S:: => Serializable
*/
?>